Collection Definitions and Custom Collections

**Referenced Files in This Document** - [.eleventy.js](file://.eleventy.js) - [news.11tydata.json](file://src/content/news/news.11tydata.json) - [cases.11tydata.json](file://src/content/cases/cases.11tydata.json) - [team.11tydata.json](file://src/content/team/team.11tydata.json) - [services.11tydata.json](file://src/content/services/services.11tydata.json) - [newsletters.11tydata.json](file://src/content/newsletters/newsletters.11tydata.json) - [knowledge.11tydata.js](file://src/content/knowledge/knowledge.11tydata.js) - [news article example](file://src/content/news/2025-10-17-political-powerhouse.md) - [case study example](file://src/content/cases/adelaide-city-fc.md) - [team member example](file://src/content/team/01-matt-neagle.md) - [News page template](file://src/news.njk) - [Cases page template](file://src/cases.njk) - [Team page template](file://src/team.njk)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document explains Eleventy’s custom collection system used in the project. It focuses on how collections are defined via the addCollection() method and how collectionApi.getFilteredByGlob() patterns select content. It documents each predefined collection (news, cases, newsletters, teamMembers, featuredNews, services, and knowledge), including their glob patterns, sorting algorithms, and filtering logic. It also provides guidance on creating custom collections, implementing complex filters, leveraging collection inheritance, optimizing performance for large datasets, and transforming data effectively.

Project Structure

Collections are configured in the Eleventy configuration file and operate on Markdown content located under src/content. Each content type has a dedicated folder and optional front matter data files that influence per-page behavior (such as permalinks and computed URLs). Templates consume these collections to render pages.

graph TB
Config[".eleventy.js<br/>Defines collections and transforms"] --> NewsGlob["src/content/news/*.md"]
Config --> CasesGlob["src/content/cases/*.md"]
Config --> NewslettersGlob["src/content/newsletters/*.md"]
Config --> TeamGlob["src/content/team/*.md"]
Config --> ServicesGlob["src/content/services/*.md"]
Config --> KnowledgeGlob["src/content/knowledge/*.md"]
NewsData["news.11tydata.json<br/>Permalink behavior"] --> NewsGlob
CasesData["cases.11tydata.json<br/>Permalink behavior"] --> CasesGlob
TeamData["team.11tydata.json<br/>Permalink behavior"] --> TeamGlob
ServicesData["services.11tydata.json<br/>Permalink behavior"] --> ServicesGlob
NewslettersData["newsletters.11tydata.json<br/>Permalink behavior"] --> NewslettersGlob
KnowledgeData["knowledge.11tydata.js<br/>Layout and computed permalink"] --> KnowledgeGlob
Templates["Nunjucks templates<br/>news.njk, cases.njk, team.njk"] --> Collections["collections.*"]
Collections --> Render["Rendered pages"]

Diagram sources

  • [.eleventy.js:166-210](file://.eleventy.js#L166-L210)
  • [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)
  • [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)
  • [services.11tydata.json:1-2](file://src/content/services/services.11tydata.json#L1-L2)
  • [newsletters.11tydata.json:1-2](file://src/content/newsletters/newsletters.11tydata.json#L1-L2)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)
  • [News page template:109-111](file://src/news.njk#L109-L111)
  • [Cases page template:32-34](file://src/cases.njk#L32-L34)
  • [Team page template:32-47](file://src/team.njk#L32-L47)

Section sources

  • [.eleventy.js:166-210](file://.eleventy.js#L166-L210)
  • [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)
  • [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)
  • [services.11tydata.json:1-2](file://src/content/services/services.11tydata.json#L1-L2)
  • [newsletters.11tydata.json:1-2](file://src/content/newsletters/newsletters.11tydata.json#L1-L2)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)

Core Components

Eleventy’s collection system centers on:

  • addCollection(name, callback): Defines a named collection using collectionApi methods.
  • collectionApi.getFilteredByGlob(pattern): Selects content files matching a glob pattern.
  • Sorting and filtering: Applied via Array.sort() and Array.filter() within collection callbacks.
  • Per-page data files: Influence permalink generation and computed properties for content pages.

Key collection definitions and their behaviors:

  • news: Glob selects Markdown under src/content/news/*.md, sorted descending by front matter date.
  • cases: Glob selects Markdown under src/content/cases/*.md.
  • newsletters: Glob selects Markdown under src/content/newsletters/*.md, sorted descending by front matter date.
  • teamMembers: Glob selects Markdown under src/content/team/*.md, sorted ascending by front matter order (fallback to a high number when absent).
  • featuredNews: Glob selects news items, filters to those marked featured, then sorts descending by date.
  • services: Glob selects Markdown under src/content/services/*.md, sorted ascending by front matter order (fallback to a high number when absent).
  • knowledge: Glob selects Markdown under src/content/knowledge/*.md, sorted descending by front matter date.

Section sources

  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)

Architecture Overview

The collection pipeline operates as follows:

  • Eleventy loads content files matched by each collection’s glob pattern.
  • Each content item is processed and enriched with front matter and computed data.
  • The collection callback applies sorting and filtering.
  • Templates iterate over collections to render pages.
sequenceDiagram
participant Eleventy as "Eleventy Runtime"
participant Config as ".eleventy.js"
participant API as "collectionApi"
participant FS as "Filesystem"
participant Page as "Content Page"
participant Template as "Nunjucks Template"
Eleventy->>Config : Load configuration
Config->>API : addCollection("news", ...)
Config->>API : addCollection("cases", ...)
Config->>API : addCollection("newsletters", ...)
Config->>API : addCollection("teamMembers", ...)
Config->>API : addCollection("featuredNews", ...)
Config->>API : addCollection("services", ...)
Config->>API : addCollection("knowledge", ...)
API->>FS : getFilteredByGlob(pattern)
FS-->>API : Matching content items
API-->>Config : Sorted/filtered collection
Config-->>Eleventy : Registered collections
Template->>Eleventy : Request collections.*
Eleventy-->>Template : Collection items
Template->>Template : Iterate and render

Diagram sources

  • [.eleventy.js:166-210](file://.eleventy.js#L166-L210)

Detailed Component Analysis

news Collection

  • Purpose: Provides chronological news articles for the News & Insights page.
  • Glob pattern: src/content/news/*.md
  • Sorting: Descending by front matter date.
  • Usage: Iterated in the News page template to render cards.

Implementation highlights:

  • Uses getFilteredByGlob() to select Markdown files.
  • Applies a comparator that converts front matter date to timestamps for accurate ordering.

Practical usage:

  • Access via collections.news in Nunjucks templates.
  • Combine with filters (e.g., category) by adding filter() within the collection callback.

Section sources

  • [.eleventy.js:170-174](file://.eleventy.js#L170-L174)
  • [News page template:109-111](file://src/news.njk#L109-L111)
  • [news article example:1-11](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L11)

cases Collection

  • Purpose: Lists case studies for the Cases page.
  • Glob pattern: src/content/cases/*.md
  • Sorting: No explicit sort; order determined by filesystem traversal and Eleventy processing.
  • Usage: Iterated in the Cases page template to render cards.

Implementation highlights:

  • Uses getFilteredByGlob() to select Markdown files.
  • Case study front matter includes category and other metadata used by the card macro.

Section sources

  • [.eleventy.js:176-179](file://.eleventy.js#L176-L179)
  • [Cases page template:32-34](file://src/cases.njk#L32-L34)
  • [case study example:1-11](file://src/content/cases/adelaide-city-fc.md#L1-L11)

newsletters Collection

  • Purpose: Manages newsletter content for subscription and archive pages.
  • Glob pattern: src/content/newsletters/*.md
  • Sorting: Descending by front matter date.
  • Usage: Typically paginated or filtered by tags in templates.

Implementation highlights:

  • Uses getFilteredByGlob() to select Markdown files.
  • Front matter includes tags for categorization and filtering.

Section sources

  • [.eleventy.js:181-185](file://.eleventy.js#L181-L185)
  • [newsletters.11tydata.json:1-2](file://src/content/newsletters/newsletters.11tydata.json#L1-L2)

teamMembers Collection

  • Purpose: Renders team profiles on the Team page.
  • Glob pattern: src/content/team/*.md
  • Sorting: Ascending by front matter order; missing order values are treated as a high number to place them last.
  • Usage: Iterated in the Team page template to render profile blocks.

Implementation highlights:

  • Uses getFilteredByGlob() to select Markdown files.
  • Sorting leverages numeric comparison with a fallback value.

Section sources

  • [.eleventy.js:187-191](file://.eleventy.js#L187-L191)
  • [team member example:1-12](file://src/content/team/01-matt-neagle.md#L1-L12)
  • [Team page template:32-47](file://src/team.njk#L32-L47)

featuredNews Collection

  • Purpose: Provides a curated subset of featured news items.
  • Glob pattern: src/content/news/*.md
  • Filtering: Items where front matter featured equals true.
  • Sorting: Descending by front matter date.
  • Usage: Ideal for highlighting top stories on landing or news pages.

Implementation highlights:

  • Chains getFilteredByGlob(), filter(), and sort().
  • Relies on front matter boolean flag for selection.

Section sources

  • [.eleventy.js:193-198](file://.eleventy.js#L193-L198)
  • [news article example](file://src/content/news/2025-10-17-political-powerhouse.md#L10)

services Collection

  • Purpose: Powers the Services overview page with ordered service entries.
  • Glob pattern: src/content/services/*.md
  • Sorting: Ascending by front matter order; missing order values are treated as a high number to place them last.
  • Usage: Iterated in service overview templates.

Implementation highlights:

  • Uses getFilteredByGlob() to select Markdown files.
  • Sorting leverages numeric comparison with a fallback value.

Section sources

  • [.eleventy.js:200-204](file://.eleventy.js#L200-L204)
  • [services.11tydata.json:1-2](file://src/content/services/services.11tydata.json#L1-L2)

knowledge Collection

  • Purpose: Manages knowledge base articles with custom permalink behavior.
  • Glob pattern: src/content/knowledge/*.md
  • Sorting: Descending by front matter date.
  • Permalink behavior: Computed via eleventyComputed to build SEO-friendly URLs under an alliance members area.

Implementation highlights:

  • Uses getFilteredByGlob() to select Markdown files.
  • Permalink is generated dynamically based on the page’s file slug.

Section sources

  • [.eleventy.js:206-210](file://.eleventy.js#L206-L210)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)

Content Data Files and Permalinks

  • news.11tydata.json: Disables default permalinks for news content.
  • cases.11tydata.json: Disables default permalinks for case studies.
  • team.11tydata.json: Disables default permalinks for team profiles.
  • services.11tydata.json: Disables default permalinks for services.
  • newsletters.11tydata.json: Disables default permalinks and adds a tag for categorization.
  • knowledge.11tydata.js: Sets layout and computes permalink using the page’s file slug.

These files influence how content pages are generated and accessed, complementing the collection logic.

Section sources

  • [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)
  • [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)
  • [services.11tydata.json:1-2](file://src/content/services/services.11tydata.json#L1-L2)
  • [newsletters.11tydata.json:1-2](file://src/content/newsletters/newsletters.11tydata.json#L1-L2)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)

Dependency Analysis

Collections depend on:

  • Filesystem content under src/content//*.md.
  • Front matter fields used for sorting and filtering (date, order, featured).
  • Optional data files that alter permalink behavior and computed properties.
graph LR
News[".eleventy.js: news"] --> NGlob["src/content/news/*.md"]
Cases[".eleventy.js: cases"] --> CGlob["src/content/cases/*.md"]
Newsletters[".eleventy.js: newsletters"] --> NLglob["src/content/newsletters/*.md"]
Team[".eleventy.js: teamMembers"] --> TGlob["src/content/team/*.md"]
Featured[".eleventy.js: featuredNews"] --> NGlob
Services[".eleventy.js: services"] --> SGlob["src/content/services/*.md"]
Knowledge[".eleventy.js: knowledge"] --> KGlob["src/content/knowledge/*.md"]
NGlob --> NData["news.11tydata.json"]
CGlob --> CData["cases.11tydata.json"]
TGlob --> TData["team.11tydata.json"]
SGlob --> SData["services.11tydata.json"]
NLglob --> NLData["newsletters.11tydata.json"]
KGlob --> KData["knowledge.11tydata.js"]

Diagram sources

  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)
  • [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)
  • [services.11tydata.json:1-2](file://src/content/services/services.11tydata.json#L1-L2)
  • [newsletters.11tydata.json:1-2](file://src/content/newsletters/newsletters.11tydata.json#L1-L2)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)

Section sources

  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)

Performance Considerations

  • Prefer precise glob patterns to minimize unnecessary file scanning.
  • Use filter() judiciously; apply early filtering in the collection callback to reduce downstream iterations.
  • Avoid expensive computations inside loops in templates; precompute where possible in collection callbacks.
  • For large datasets, consider pagination or limiting visible items in templates.
  • Keep front matter minimal and consistent to streamline sorting and filtering.
  • Use eleventyComputed sparingly; compute only what is needed for rendering.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Empty collections: Verify glob patterns and that content files exist under the expected paths.
  • Incorrect sorting: Ensure front matter date fields are valid ISO-like strings and order fields are numeric.
  • Missing featured items: Confirm front matter featured is set to true for desired items.
  • Permalink mismatches: Review data files for permalink overrides and computed properties.

Section sources

  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • [news article example:3-10](file://src/content/news/2025-10-17-political-powerhouse.md#L3-L10)
  • [team member example:5-11](file://src/content/team/01-matt-neagle.md#L5-L11)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L4-L6)

Conclusion

The project’s collection system cleanly separates content discovery (glob patterns), transformation (sorting and filtering), and presentation (templates). By leveraging front matter and data files, it supports flexible, maintainable content architectures. Following the best practices outlined here ensures reliable performance and scalability as content grows.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Creating Custom Collections

Steps to define a new collection:

  • Choose a descriptive name and a glob pattern targeting your content directory.
  • Implement addCollection() with getFilteredByGlob() and chain sort()/filter() as needed.
  • Reference the collection in templates via collections..
  • Optionally add a data file to control permalink behavior for the content type.

Example references:

  • Collection definition pattern: [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • Template usage pattern: [News page template:109-111](file://src/news.njk#L109-L111), [Cases page template:32-34](file://src/cases.njk#L32-L34), [Team page template:32-47](file://src/team.njk#L32-L47)

Section sources

  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • [News page template:109-111](file://src/news.njk#L109-L111)
  • [Cases page template:32-34](file://src/cases.njk#L32-L34)
  • [Team page template:32-47](file://src/team.njk#L32-L47)

Complex Filtering Conditions

Examples of advanced filtering you can implement within collection callbacks:

  • Multi-property filtering: Combine filter() with multiple front matter checks.
  • Category-based subsets: Filter by tags or categories present in front matter.
  • Date windows: Filter items within a date range using date comparisons.
  • Fallbacks and defaults: Use default values for missing front matter fields to ensure consistent sorting.

Reference patterns:

  • Filtering by boolean flag: [.eleventy.js:193-198](file://.eleventy.js#L193-L198)
  • Numeric ordering fallback: [.eleventy.js:187-191](file://.eleventy.js#L187-L191), [.eleventy.js:200-204](file://.eleventy.js#L200-L204)

Section sources

  • [.eleventy.js:193-198](file://.eleventy.js#L193-L198)
  • [.eleventy.js:187-191](file://.eleventy.js#L187-L191)
  • [.eleventy.js:200-204](file://.eleventy.js#L200-L204)

Collection Inheritance and Data Files

How data files influence collections:

  • Disable default permalinks or set custom ones via eleventyComputed.
  • Add tags for taxonomy-based filtering.
  • Control layout assignments for content types.

References:

  • Knowledge collection permalink computation: [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)
  • Newsletter tags and permalinks: [newsletters.11tydata.json:1-2](file://src/content/newsletters/newsletters.11tydata.json#L1-L2)
  • Other content data files: [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2), [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2), [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2), [services.11tydata.json:1-2](file://src/content/services/services.11tydata.json#L1-L2)

Section sources

  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)
  • [newsletters.11tydata.json:1-2](file://src/content/newsletters/newsletters.11tydata.json#L1-L2)
  • [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)
  • [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)
  • [services.11tydata.json:1-2](file://src/content/services/services.11tydata.json#L1-L2)

Practical Transformations and Data Manipulation

Techniques to enrich collections:

  • Precompute derived values in collection callbacks (e.g., reading time, excerpts).
  • Normalize front matter values to ensure consistent sorting and filtering.
  • Paginate large collections in templates to improve rendering performance.

[No sources needed since this section provides general guidance]